blob: 90c73d6708b1d7dc90f50380c20521a1f713ff90 [file] [log] [blame]
Junio C Hamanob0e02952008-01-19 08:02:001Commit Limiting
2~~~~~~~~~~~~~~~
3
4Besides specifying a range of commits that should be listed using the
5special notations explained in the description, additional commit
Junio C Hamano8ce35d72012-09-18 22:30:426limiting may be applied.
7
8Using more options generally further limits the output (e.g.
9`--since=<date1>` limits to commits newer than `<date1>`, and using it
10with `--grep=<pattern>` further limits to commits whose log message
11has a line that matches `<pattern>`), unless otherwise noted.
12
13Note that these are applied before commit
14ordering and formatting options, such as `--reverse`.
Junio C Hamanob0e02952008-01-19 08:02:0015
Junio C Hamano693e7092012-09-12 22:56:5316-<number>::
17-n <number>::
Junio C Hamanob4a9ede2009-04-08 07:36:3218--max-count=<number>::
Junio C Hamanoc5be4cc2011-03-09 07:20:4319Limit the number of commits to output.
Junio C Hamanob0e02952008-01-19 08:02:0020
Junio C Hamanob4a9ede2009-04-08 07:36:3221--skip=<number>::
Junio C Hamanob0e02952008-01-19 08:02:0022Skip 'number' commits before starting to show the commit output.
23
Junio C Hamanob4a9ede2009-04-08 07:36:3224--since=<date>::
25--after=<date>::
Junio C Hamanob0e02952008-01-19 08:02:0026Show commits more recent than a specific date.
27
Junio C Hamano72ea2ca2022-05-21 00:51:2328--since-as-filter=<date>::
29Show all commits more recent than a specific date. This visits
30all commits in the range, rather than stopping at the first commit which
31is older than a specific date.
32
Junio C Hamanob4a9ede2009-04-08 07:36:3233--until=<date>::
34--before=<date>::
Junio C Hamanob0e02952008-01-19 08:02:0035Show commits older than a specific date.
36
Junio C Hamano4f1d8c42008-03-03 02:01:1637ifdef::git-rev-list[]
Junio C Hamanob4a9ede2009-04-08 07:36:3238--max-age=<timestamp>::
39--min-age=<timestamp>::
Junio C Hamanob0e02952008-01-19 08:02:0040Limit the commits output to specified time range.
Junio C Hamano4f1d8c42008-03-03 02:01:1641endif::git-rev-list[]
Junio C Hamanob0e02952008-01-19 08:02:0042
Junio C Hamanob4a9ede2009-04-08 07:36:3243--author=<pattern>::
44--committer=<pattern>::
Junio C Hamanob0e02952008-01-19 08:02:0045Limit the commits output to ones with author/committer
Junio C Hamano8ce35d72012-09-18 22:30:4246header lines that match the specified pattern (regular
47expression). With more than one `--author=<pattern>`,
48commits whose author matches any of the given patterns are
49chosen (similarly for multiple `--committer=<pattern>`).
Junio C Hamanob0e02952008-01-19 08:02:0050
Junio C Hamano9954ed72012-10-03 04:54:0051--grep-reflog=<pattern>::
Junio C Hamano9954ed72012-10-03 04:54:0052Limit the commits output to ones with reflog entries that
53match the specified pattern (regular expression). With
54more than one `--grep-reflog`, commits whose reflog message
55matches any of the given patterns are chosen. It is an
56error to use this option unless `--walk-reflogs` is in use.
57
Junio C Hamanob4a9ede2009-04-08 07:36:3258--grep=<pattern>::
Junio C Hamanob0e02952008-01-19 08:02:0059Limit the commits output to ones with log message that
Junio C Hamano8ce35d72012-09-18 22:30:4260matches the specified pattern (regular expression). With
61more than one `--grep=<pattern>`, commits whose message
62matches any of the given patterns are chosen (but see
63`--all-match`).
Junio C Hamano3891e252015-08-31 23:06:1364ifndef::git-rev-list[]
Junio C Hamano9954ed72012-10-03 04:54:0065+
Junio C Hamanob3f862c2019-12-05 22:22:0066When `--notes` is in effect, the message from the notes is
Junio C Hamano8152abf2015-04-28 22:48:0267matched as if it were part of the log message.
Junio C Hamano3891e252015-08-31 23:06:1368endif::git-rev-list[]
Junio C Hamanob0e02952008-01-19 08:02:0069
Junio C Hamanoaa17c7c2008-11-03 04:36:5870--all-match::
Junio C Hamanob73af6c2013-12-03 22:07:1171Limit the commits output to ones that match all given `--grep`,
Junio C Hamano8ce35d72012-09-18 22:30:4272instead of ones that match at least one.
Junio C Hamanoaa17c7c2008-11-03 04:36:5873
Junio C Hamano6bb32e62015-02-17 22:11:2674--invert-grep::
75Limit the commits output to ones with log message that do not
76match the pattern specified with `--grep=<pattern>`.
77
Junio C Hamanoeb415992008-06-08 22:49:4778-i::
79--regexp-ignore-case::
Junio C Hamanob73af6c2013-12-03 22:07:1180Match the regular expression limiting patterns without regard to letter
81case.
Junio C Hamanob0e02952008-01-19 08:02:0082
Junio C Hamanoa1295452012-11-13 22:32:0483--basic-regexp::
Junio C Hamanoa1295452012-11-13 22:32:0484Consider the limiting patterns to be basic regular expressions;
85this is the default.
86
Junio C Hamanoeb415992008-06-08 22:49:4787-E::
88--extended-regexp::
Junio C Hamanob0e02952008-01-19 08:02:0089Consider the limiting patterns to be extended regular expressions
90instead of the default basic regular expressions.
91
Junio C Hamanoeb415992008-06-08 22:49:4792-F::
93--fixed-strings::
Junio C Hamano24bc09a2008-02-28 00:27:4494Consider the limiting patterns to be fixed strings (don't interpret
95pattern as a regular expression).
96
Junio C Hamanoa275c1f2017-06-19 20:10:1297-P::
Junio C Hamanoa1295452012-11-13 22:32:0498--perl-regexp::
Junio C Hamano222ed822017-06-02 06:24:0699Consider the limiting patterns to be Perl-compatible regular
100expressions.
101+
102Support for these types of regular expressions is an optional
103compile-time dependency. If Git wasn't compiled with support for them
104providing this option will cause it to die.
Junio C Hamanoa1295452012-11-13 22:32:04105
Junio C Hamanob0e02952008-01-19 08:02:00106--remove-empty::
Junio C Hamanob0e02952008-01-19 08:02:00107Stop when a given path disappears from the tree.
108
Junio C Hamano934e1782009-07-16 06:59:15109--merges::
Junio C Hamanof32ce262011-03-27 07:35:11110Print only merge commits. This is exactly the same as `--min-parents=2`.
Junio C Hamano934e1782009-07-16 06:59:15111
Junio C Hamanob0e02952008-01-19 08:02:00112--no-merges::
Junio C Hamanof32ce262011-03-27 07:35:11113Do not print commits with more than one parent. This is
114exactly the same as `--max-parents=1`.
115
116--min-parents=<number>::
117--max-parents=<number>::
118--no-min-parents::
119--no-max-parents::
Junio C Hamanoc5bb3b32013-08-05 22:43:36120Show only commits which have at least (or at most) that many parent
Junio C Hamanof32ce262011-03-27 07:35:11121commits. In particular, `--max-parents=1` is the same as `--no-merges`,
122`--min-parents=2` is the same as `--merges`. `--max-parents=0`
123gives all root commits and `--min-parents=3` all octopus merges.
124+
125`--no-min-parents` and `--no-max-parents` reset these limits (to no limit)
126again. Equivalent forms are `--min-parents=0` (any commit has 0 or more
127parents) and `--max-parents=-1` (negative numbers denote no upper limit).
Junio C Hamanob0e02952008-01-19 08:02:00128
129--first-parent::
Junio C Hamano034a2ff2022-02-18 00:40:11130When finding commits to include, follow only the first
131parent commit upon seeing a merge commit. This option
132can give a better overview when viewing the evolution of
133a particular topic branch, because merges into a topic
134branch tend to be only about adjusting to updated upstream
135from time to time, and this option allows you to ignore
136the individual commits brought in to your history by such
137a merge.
Junio C Hamano8c860d62021-02-06 01:37:47138ifdef::git-log[]
Junio C Hamanoa372d5b2021-02-26 01:34:37139+
140This option also changes default diff format for merge commits
141to `first-parent`, see `--diff-merges=first-parent` for details.
Junio C Hamano8c860d62021-02-06 01:37:47142endif::git-log[]
143
Junio C Hamano034a2ff2022-02-18 00:40:11144--exclude-first-parent-only::
145When finding commits to exclude (with a '{caret}'), follow only
146the first parent commit upon seeing a merge commit.
147This can be used to find the set of changes in a topic branch
148from the point where it diverged from the remote branch, given
149that arbitrary merges can be valid topic branch changes.
150
Junio C Hamanob0e02952008-01-19 08:02:00151--not::
Junio C Hamanob0e02952008-01-19 08:02:00152Reverses the meaning of the '{caret}' prefix (or lack thereof)
Junio C Hamanob73af6c2013-12-03 22:07:11153for all following revision specifiers, up to the next `--not`.
Junio C Hamanob0e02952008-01-19 08:02:00154
155--all::
Junio C Hamanoe89102f2017-02-15 23:18:15156Pretend as if all the refs in `refs/`, along with `HEAD`, are
157listed on the command line as '<commit>'.
Junio C Hamanob0e02952008-01-19 08:02:00158
Junio C Hamanod2179ef2010-10-22 04:12:17159--branches[=<pattern>]::
Junio C Hamano4fdccb22010-02-19 09:58:14160Pretend as if all the refs in `refs/heads` are listed
Junio C Hamanod2179ef2010-10-22 04:12:17161on the command line as '<commit>'. If '<pattern>' is given, limit
Junio C Hamano57827fb2010-01-23 03:02:50162branches to ones matching given shell glob. If pattern lacks '?',
Junio C Hamano81d540a2012-03-02 19:52:47163'{asterisk}', or '[', '/{asterisk}' at the end is implied.
Junio C Hamano50819852008-11-19 02:07:56164
Junio C Hamanod2179ef2010-10-22 04:12:17165--tags[=<pattern>]::
Junio C Hamano4fdccb22010-02-19 09:58:14166Pretend as if all the refs in `refs/tags` are listed
Junio C Hamanod2179ef2010-10-22 04:12:17167on the command line as '<commit>'. If '<pattern>' is given, limit
Junio C Hamano81d540a2012-03-02 19:52:47168tags to ones matching given shell glob. If pattern lacks '?', '{asterisk}',
169or '[', '/{asterisk}' at the end is implied.
Junio C Hamano50819852008-11-19 02:07:56170
Junio C Hamanod2179ef2010-10-22 04:12:17171--remotes[=<pattern>]::
Junio C Hamano4fdccb22010-02-19 09:58:14172Pretend as if all the refs in `refs/remotes` are listed
Junio C Hamanod2179ef2010-10-22 04:12:17173on the command line as '<commit>'. If '<pattern>' is given, limit
Junio C Hamano97bcb482010-11-25 03:16:07174remote-tracking branches to ones matching given shell glob.
Junio C Hamano81d540a2012-03-02 19:52:47175If pattern lacks '?', '{asterisk}', or '[', '/{asterisk}' at the end is implied.
Junio C Hamano57827fb2010-01-23 03:02:50176
Junio C Hamanod2179ef2010-10-22 04:12:17177--glob=<glob-pattern>::
178Pretend as if all the refs matching shell glob '<glob-pattern>'
Junio C Hamano57827fb2010-01-23 03:02:50179are listed on the command line as '<commit>'. Leading 'refs/',
Junio C Hamano81d540a2012-03-02 19:52:47180is automatically prepended if missing. If pattern lacks '?', '{asterisk}',
181or '[', '/{asterisk}' at the end is implied.
Junio C Hamano57827fb2010-01-23 03:02:50182
Junio C Hamanof079f702013-12-06 23:43:18183--exclude=<glob-pattern>::
184
185Do not include refs matching '<glob-pattern>' that the next `--all`,
186`--branches`, `--tags`, `--remotes`, or `--glob` would otherwise
187consider. Repetitions of this option accumulate exclusion patterns
188up to the next `--all`, `--branches`, `--tags`, `--remotes`, or
189`--glob` option (other options or arguments do not clear
Junio C Hamanofb5ffde2014-11-04 22:38:56190accumulated patterns).
Junio C Hamanof079f702013-12-06 23:43:18191+
192The patterns given should not begin with `refs/heads`, `refs/tags`, or
193`refs/remotes` when applied to `--branches`, `--tags`, or `--remotes`,
194respectively, and they must begin with `refs/` when applied to `--glob`
195or `--all`. If a trailing '/{asterisk}' is intended, it must be given
196explicitly.
197
Junio C Hamano42ce67d2023-03-17 21:36:41198--exclude-hidden=[fetch|receive|uploadpack]::
199Do not include refs that would be hidden by `git-fetch`,
200`git-receive-pack` or `git-upload-pack` by consulting the appropriate
201`fetch.hideRefs`, `receive.hideRefs` or `uploadpack.hideRefs`
202configuration along with `transfer.hideRefs` (see
Junio C Hamanoe6ab9192022-11-23 04:01:36203linkgit:git-config[1]). This option affects the next pseudo-ref option
204`--all` or `--glob` and is cleared after processing them.
205
Junio C Hamano2a4bcbc2014-10-29 20:07:39206--reflog::
207Pretend as if all objects mentioned by reflogs are listed on the
208command line as `<commit>`.
209
Junio C Hamanoa42e0332019-07-19 19:49:37210--alternate-refs::
211Pretend as if all objects mentioned as ref tips of alternate
212repositories were listed on the command line. An alternate
213repository is any repository whose object directory is specified
214in `objects/info/alternates`. The set of included objects may
215be modified by `core.alternateRefsCommand`, etc. See
216linkgit:git-config[1].
217
Junio C Hamano8d57fa92017-09-19 05:01:08218--single-worktree::
219By default, all working trees will be examined by the
220following options when there are more than one (see
221linkgit:git-worktree[1]): `--all`, `--reflog` and
222`--indexed-objects`.
223This option forces them to examine the current working tree
224only.
225
Junio C Hamano084228c2011-05-30 08:13:52226--ignore-missing::
Junio C Hamano084228c2011-05-30 08:13:52227Upon seeing an invalid object name in the input, pretend as if
228the bad input was not given.
Junio C Hamano50819852008-11-19 02:07:56229
Junio C Hamano5706e0b2009-11-24 10:54:16230ifndef::git-rev-list[]
231--bisect::
Junio C Hamano4fdccb22010-02-19 09:58:14232Pretend as if the bad bisection ref `refs/bisect/bad`
Junio C Hamano5706e0b2009-11-24 10:54:16233was listed and as if it was followed by `--not` and the good
Junio C Hamano4fdccb22010-02-19 09:58:14234bisection refs `refs/bisect/good-*` on the command
Junio C Hamano255163d2020-08-18 00:37:23235line.
Junio C Hamano5706e0b2009-11-24 10:54:16236endif::git-rev-list[]
237
Junio C Hamanob0e02952008-01-19 08:02:00238--stdin::
Junio C Hamanob0e02952008-01-19 08:02:00239In addition to the '<commit>' listed on the command
Junio C Hamano92d80372016-07-13 22:00:05240line, read them from the standard input. If a `--` separator is
Junio C Hamano5706e0b2009-11-24 10:54:16241seen, stop reading commits and start reading paths to limit the
242result.
Junio C Hamanob0e02952008-01-19 08:02:00243
Junio C Hamano5706e0b2009-11-24 10:54:16244ifdef::git-rev-list[]
Junio C Hamanob0e02952008-01-19 08:02:00245--quiet::
Junio C Hamanob0e02952008-01-19 08:02:00246Don't print anything to standard output. This form
247is primarily meant to allow the caller to
248test the exit status to see if a range of objects is fully
249connected (or not). It is faster than redirecting stdout
Junio C Hamanob73af6c2013-12-03 22:07:11250to `/dev/null` as the output does not have to be formatted.
Junio C Hamanoa372d5b2021-02-26 01:34:37251
252--disk-usage::
Junio C Hamano04495a12022-08-18 21:13:08253--disk-usage=human::
Junio C Hamanoa372d5b2021-02-26 01:34:37254Suppress normal output; instead, print the sum of the bytes used
255for on-disk storage by the selected commits or objects. This is
256equivalent to piping the output into `git cat-file
257--batch-check='%(objectsize:disk)'`, except that it runs much
258faster (especially with `--use-bitmap-index`). See the `CAVEATS`
259section in linkgit:git-cat-file[1] for the limitations of what
260"on-disk storage" means.
Junio C Hamano04495a12022-08-18 21:13:08261With the optional value `human`, on-disk storage size is shown
262in human-readable string(e.g. 12.24 Kib, 3.50 Mib).
Junio C Hamano69cd7c52008-06-04 07:52:59263endif::git-rev-list[]
Junio C Hamanob0e02952008-01-19 08:02:00264
Junio C Hamano9a2fb2d2011-03-23 05:40:15265--cherry-mark::
Junio C Hamano9a2fb2d2011-03-23 05:40:15266Like `--cherry-pick` (see below) but mark equivalent commits
267with `=` rather than omitting them, and inequivalent ones with `+`.
268
Junio C Hamanob0e02952008-01-19 08:02:00269--cherry-pick::
Junio C Hamanob0e02952008-01-19 08:02:00270Omit any commit that introduces the same change as
Junio C Hamanob73af6c2013-12-03 22:07:11271another commit on the ``other side'' when the set of
Junio C Hamanob0e02952008-01-19 08:02:00272commits are limited with symmetric difference.
273+
274For example, if you have two branches, `A` and `B`, a usual way
275to list all commits on only one side of them is with
Junio C Hamano5cd15182011-04-05 00:21:10276`--left-right` (see the example below in the description of
Junio C Hamanob73af6c2013-12-03 22:07:11277the `--left-right` option). However, it shows the commits that were
278cherry-picked from the other branch (for example, ``3rd on b'' may be
279cherry-picked from branch A). With this option, such pairs of commits are
Junio C Hamanob0e02952008-01-19 08:02:00280excluded from the output.
281
Junio C Hamano9a2fb2d2011-03-23 05:40:15282--left-only::
283--right-only::
Junio C Hamanocd451662016-09-13 00:54:09284List only commits on the respective side of a symmetric difference,
Junio C Hamano9a2fb2d2011-03-23 05:40:15285i.e. only those which would be marked `<` resp. `>` by
286`--left-right`.
287+
288For example, `--cherry-pick --right-only A...B` omits those
289commits from `B` which are in `A` or are patch-equivalent to a commit in
Junio C Hamanob76a6862012-05-02 22:02:46290`A`. In other words, this lists the `+` commits from `git cherry A B`.
Junio C Hamano9a2fb2d2011-03-23 05:40:15291More precisely, `--cherry-pick --right-only --no-merges` gives the exact
292list.
293
294--cherry::
Junio C Hamano9a2fb2d2011-03-23 05:40:15295A synonym for `--right-only --cherry-mark --no-merges`; useful to
296limit the output to the commits on our side and mark those that
297have been applied to the other side of a forked history with
298`git log --cherry upstream...mybranch`, similar to
299`git cherry upstream mybranch`.
300
Junio C Hamanoeb415992008-06-08 22:49:47301-g::
302--walk-reflogs::
Junio C Hamanob0e02952008-01-19 08:02:00303Instead of walking the commit ancestry chain, walk
304reflog entries from the most recent one to older ones.
305When this option is used you cannot specify commits to
306exclude (that is, '{caret}commit', 'commit1..commit2',
Junio C Hamanod75148a2014-04-08 19:48:38307and 'commit1\...commit2' notations cannot be used).
Junio C Hamanob0e02952008-01-19 08:02:00308+
Junio C Hamanob4896852019-12-10 23:15:09309With `--pretty` format other than `oneline` and `reference` (for obvious reasons),
Junio C Hamanob0e02952008-01-19 08:02:00310this causes the output to have two extra lines of information
Junio C Hamanoe548d1b2016-08-08 22:26:49311taken from the reflog. The reflog designator in the output may be shown
312as `ref@{Nth}` (where `Nth` is the reverse-chronological index in the
313reflog) or as `ref@{timestamp}` (with the timestamp for that entry),
314depending on a few rules:
315+
316--
3171. If the starting point is specified as `ref@{Nth}`, show the index
Junio C Hamano2567b322019-02-05 23:33:56318 format.
Junio C Hamanoe548d1b2016-08-08 22:26:49319+
3202. If the starting point was specified as `ref@{now}`, show the
Junio C Hamano2567b322019-02-05 23:33:56321 timestamp format.
Junio C Hamanoe548d1b2016-08-08 22:26:49322+
3233. If neither was used, but `--date` was given on the command line, show
Junio C Hamano2567b322019-02-05 23:33:56324 the timestamp in the format requested by `--date`.
Junio C Hamanoe548d1b2016-08-08 22:26:49325+
3264. Otherwise, show the index format.
327--
328+
329Under `--pretty=oneline`, the commit message is
Junio C Hamanob0e02952008-01-19 08:02:00330prefixed with this information on the same line.
Junio C Hamanob73af6c2013-12-03 22:07:11331This option cannot be combined with `--reverse`.
Junio C Hamanob0e02952008-01-19 08:02:00332See also linkgit:git-reflog[1].
Junio C Hamanob4896852019-12-10 23:15:09333+
334Under `--pretty=reference`, this information will not be shown at all.
Junio C Hamanob0e02952008-01-19 08:02:00335
336--merge::
Junio C Hamanob0e02952008-01-19 08:02:00337After a failed merge, show refs that touch files having a
338conflict and don't exist on all heads to merge.
339
340--boundary::
Junio C Hamano27159f82013-06-14 17:19:22341Output excluded boundary commits. Boundary commits are
342prefixed with `-`.
Junio C Hamanob0e02952008-01-19 08:02:00343
Junio C Hamano5b3533d2014-02-27 23:07:15344ifdef::git-rev-list[]
345--use-bitmap-index::
346
347Try to speed up the traversal using the pack bitmap index (if
348one is available). Note that when traversing with `--objects`,
349trees and blobs will not have their associated path printed.
Junio C Hamanoe48a1132016-08-03 22:40:21350
351--progress=<header>::
352Show progress reports on stderr as objects are considered. The
353`<header>` text will be printed with each progress update.
Junio C Hamano5b3533d2014-02-27 23:07:15354endif::git-rev-list[]
355
Junio C Hamanoa76cb0d2008-08-13 20:04:10356History Simplification
357~~~~~~~~~~~~~~~~~~~~~~
358
Junio C Hamano28363492008-11-14 08:26:31359Sometimes you are only interested in parts of the history, for example the
360commits modifying a particular <path>. But there are two parts of
361'History Simplification', one part is selecting the commits and the other
362is how to do it, as there are various strategies to simplify the history.
363
364The following options select the commits to be shown:
365
366<paths>::
Junio C Hamano28363492008-11-14 08:26:31367Commits modifying the given <paths> are selected.
368
369--simplify-by-decoration::
Junio C Hamano28363492008-11-14 08:26:31370Commits that are referred by some branch or tag are selected.
371
372Note that extra commits can be shown to give a meaningful history.
373
374The following options affect the way the simplification is performed:
375
376Default mode::
Junio C Hamano28363492008-11-14 08:26:31377Simplifies the history to the simplest history explaining the
378final state of the tree. Simplest because it prunes some side
379branches if the end result is the same (i.e. merging branches
380with the same content)
381
Junio C Hamano67bf2242020-04-22 21:41:44382--show-pulls::
383Include all commits from the default mode, but also any merge
384commits that are not TREESAME to the first parent but are
385TREESAME to a later parent. This mode is helpful for showing
386the merge commits that "first introduced" a change to a branch.
387
Junio C Hamano28363492008-11-14 08:26:31388--full-history::
Junio C Hamano15567bc2011-07-23 00:51:59389Same as the default mode, but does not prune some history.
Junio C Hamano28363492008-11-14 08:26:31390
391--dense::
Junio C Hamano28363492008-11-14 08:26:31392Only the selected commits are shown, plus some to have a
393meaningful history.
394
395--sparse::
Junio C Hamano28363492008-11-14 08:26:31396All commits in the simplified history are shown.
397
398--simplify-merges::
Junio C Hamanob73af6c2013-12-03 22:07:11399Additional option to `--full-history` to remove some needless
Junio C Hamano28363492008-11-14 08:26:31400merges from the resulting history, as there are no selected
401commits contributing to this merge.
402
Junio C Hamano594d2d42022-08-30 17:58:50403--ancestry-path[=<commit>]::
Junio C Hamano89a57342010-06-22 23:22:55404When given a range of commits to display (e.g. 'commit1..commit2'
Junio C Hamano594d2d42022-08-30 17:58:50405or 'commit2 {caret}commit1'), only display commits in that range
406that are ancestors of <commit>, descendants of <commit>, or
407<commit> itself. If no commit is specified, use 'commit1' (the
408excluded part of the range) as <commit>. Can be passed multiple
409times; if so, a commit is included if it is any of the commits
410given or if it is an ancestor or descendant of one of them.
Junio C Hamano89a57342010-06-22 23:22:55411
Junio C Hamano28363492008-11-14 08:26:31412A more detailed explanation follows.
Junio C Hamanoa76cb0d2008-08-13 20:04:10413
414Suppose you specified `foo` as the <paths>. We shall call commits
415that modify `foo` !TREESAME, and the rest TREESAME. (In a diff
416filtered for `foo`, they look different and equal, respectively.)
417
418In the following, we will always refer to the same example history to
419illustrate the differences between simplification settings. We assume
420that you are filtering for a file `foo` in this commit graph:
421-----------------------------------------------------------------------
Junio C Hamano27159f82013-06-14 17:19:22422 .-A---M---N---O---P---Q
423 / / / / / /
424I B C D E Y
425 \ / / / / /
426 `-------------' X
Junio C Hamanoa76cb0d2008-08-13 20:04:10427-----------------------------------------------------------------------
Junio C Hamano27159f82013-06-14 17:19:22428The horizontal line of history A---Q is taken to be the first parent of
Junio C Hamanoa76cb0d2008-08-13 20:04:10429each merge. The commits are:
430
431* `I` is the initial commit, in which `foo` exists with contents
Junio C Hamanob73af6c2013-12-03 22:07:11432 ``asdf'', and a file `quux` exists with contents ``quux''. Initial
Junio C Hamanoa76cb0d2008-08-13 20:04:10433 commits are compared to an empty tree, so `I` is !TREESAME.
434
Junio C Hamanob73af6c2013-12-03 22:07:11435* In `A`, `foo` contains just ``foo''.
Junio C Hamanoa76cb0d2008-08-13 20:04:10436
437* `B` contains the same change as `A`. Its merge `M` is trivial and
438 hence TREESAME to all parents.
439
Junio C Hamanob73af6c2013-12-03 22:07:11440* `C` does not change `foo`, but its merge `N` changes it to ``foobar'',
Junio C Hamanoa76cb0d2008-08-13 20:04:10441 so it is not TREESAME to any parent.
442
Junio C Hamanob73af6c2013-12-03 22:07:11443* `D` sets `foo` to ``baz''. Its merge `O` combines the strings from
444 `N` and `D` to ``foobarbaz''; i.e., it is not TREESAME to any parent.
Junio C Hamanoa76cb0d2008-08-13 20:04:10445
Junio C Hamanob73af6c2013-12-03 22:07:11446* `E` changes `quux` to ``xyzzy'', and its merge `P` combines the
447 strings to ``quux xyzzy''. `P` is TREESAME to `O`, but not to `E`.
Junio C Hamano27159f82013-06-14 17:19:22448
Junio C Hamanod7fccbf2013-07-25 03:24:57449* `X` is an independent root commit that added a new file `side`, and `Y`
Junio C Hamano27159f82013-06-14 17:19:22450 modified it. `Y` is TREESAME to `X`. Its merge `Q` added `side` to `P`, and
451 `Q` is TREESAME to `P`, but not to `Y`.
Junio C Hamanoa76cb0d2008-08-13 20:04:10452
Junio C Hamanob73af6c2013-12-03 22:07:11453`rev-list` walks backwards through history, including or excluding
454commits based on whether `--full-history` and/or parent rewriting
455(via `--parents` or `--children`) are used. The following settings
Junio C Hamanoa76cb0d2008-08-13 20:04:10456are available.
457
458Default mode::
Junio C Hamanoa76cb0d2008-08-13 20:04:10459Commits are included if they are not TREESAME to any parent
Junio C Hamanob73af6c2013-12-03 22:07:11460(though this can be changed, see `--sparse` below). If the
Junio C Hamanoa76cb0d2008-08-13 20:04:10461commit was a merge, and it was TREESAME to one parent, follow
462only that parent. (Even if there are several TREESAME
463parents, follow only one of them.) Otherwise, follow all
464parents.
465+
466This results in:
467+
468-----------------------------------------------------------------------
469 .-A---N---O
Junio C Hamano89a57342010-06-22 23:22:55470 / / /
Junio C Hamanoa76cb0d2008-08-13 20:04:10471I---------D
472-----------------------------------------------------------------------
473+
474Note how the rule to only follow the TREESAME parent, if one is
475available, removed `B` from consideration entirely. `C` was
476considered via `N`, but is TREESAME. Root commits are compared to an
477empty tree, so `I` is !TREESAME.
478+
Junio C Hamanob73af6c2013-12-03 22:07:11479Parent/child relations are only visible with `--parents`, but that does
Junio C Hamanoa76cb0d2008-08-13 20:04:10480not affect the commits selected in default mode, so we have shown the
481parent lines.
482
483--full-history without parent rewriting::
Junio C Hamanoa76cb0d2008-08-13 20:04:10484This mode differs from the default in one point: always follow
485all parents of a merge, even if it is TREESAME to one of them.
486Even if more than one side of the merge has commits that are
487included, this does not imply that the merge itself is! In
488the example, we get
489+
490-----------------------------------------------------------------------
Junio C Hamano27159f82013-06-14 17:19:22491I A B N D O P Q
Junio C Hamanoa76cb0d2008-08-13 20:04:10492-----------------------------------------------------------------------
493+
Junio C Hamano27159f82013-06-14 17:19:22494`M` was excluded because it is TREESAME to both parents. `E`,
Junio C Hamanoa76cb0d2008-08-13 20:04:10495`C` and `B` were all walked, but only `B` was !TREESAME, so the others
496do not appear.
497+
498Note that without parent rewriting, it is not really possible to talk
499about the parent/child relationships between the commits, so we show
500them disconnected.
501
502--full-history with parent rewriting::
Junio C Hamanoa76cb0d2008-08-13 20:04:10503Ordinary commits are only included if they are !TREESAME
Junio C Hamanob73af6c2013-12-03 22:07:11504(though this can be changed, see `--sparse` below).
Junio C Hamanoa76cb0d2008-08-13 20:04:10505+
506Merges are always included. However, their parent list is rewritten:
507Along each parent, prune away commits that are not included
508themselves. This results in
509+
510-----------------------------------------------------------------------
Junio C Hamano27159f82013-06-14 17:19:22511 .-A---M---N---O---P---Q
Junio C Hamanoa76cb0d2008-08-13 20:04:10512 / / / / /
513I B / D /
514 \ / / / /
515 `-------------'
516-----------------------------------------------------------------------
517+
Junio C Hamanob73af6c2013-12-03 22:07:11518Compare to `--full-history` without rewriting above. Note that `E`
Junio C Hamanoa76cb0d2008-08-13 20:04:10519was pruned away because it is TREESAME, but the parent list of P was
520rewritten to contain `E`'s parent `I`. The same happened for `C` and
Junio C Hamano27159f82013-06-14 17:19:22521`N`, and `X`, `Y` and `Q`.
Junio C Hamanoa76cb0d2008-08-13 20:04:10522
523In addition to the above settings, you can change whether TREESAME
524affects inclusion:
525
Junio C Hamanoeb415992008-06-08 22:49:47526--dense::
Junio C Hamanoa76cb0d2008-08-13 20:04:10527Commits that are walked are included if they are not TREESAME
528to any parent.
529
Junio C Hamanoeb415992008-06-08 22:49:47530--sparse::
Junio C Hamanoa76cb0d2008-08-13 20:04:10531All commits that are walked are included.
532+
Junio C Hamanob73af6c2013-12-03 22:07:11533Note that without `--full-history`, this still simplifies merges: if
Junio C Hamanoa76cb0d2008-08-13 20:04:10534one of the parents is TREESAME, we follow only that one, so the other
535sides of the merge are never walked.
Junio C Hamanob0e02952008-01-19 08:02:00536
Junio C Hamanoa2f46622008-09-03 05:20:31537--simplify-merges::
Junio C Hamanoa2f46622008-09-03 05:20:31538First, build a history graph in the same way that
Junio C Hamanob73af6c2013-12-03 22:07:11539`--full-history` with parent rewriting does (see above).
Junio C Hamanoa2f46622008-09-03 05:20:31540+
541Then simplify each commit `C` to its replacement `C'` in the final
542history according to the following rules:
543+
544--
545* Set `C'` to `C`.
546+
547* Replace each parent `P` of `C'` with its simplification `P'`. In
Junio C Hamano27159f82013-06-14 17:19:22548 the process, drop parents that are ancestors of other parents or that are
549 root commits TREESAME to an empty tree, and remove duplicates, but take care
550 to never drop all parents that we are TREESAME to.
Junio C Hamanoa2f46622008-09-03 05:20:31551+
552* If after this parent rewriting, `C'` is a root or merge commit (has
553 zero or >1 parents), a boundary commit, or !TREESAME, it remains.
554 Otherwise, it is replaced with its only parent.
555--
556+
557The effect of this is best shown by way of comparing to
Junio C Hamanob73af6c2013-12-03 22:07:11558`--full-history` with parent rewriting. The example turns into:
Junio C Hamanoa2f46622008-09-03 05:20:31559+
560-----------------------------------------------------------------------
561 .-A---M---N---O
562 / / /
563I B D
564 \ / /
565 `---------'
566-----------------------------------------------------------------------
567+
Junio C Hamanob73af6c2013-12-03 22:07:11568Note the major differences in `N`, `P`, and `Q` over `--full-history`:
Junio C Hamanoa2f46622008-09-03 05:20:31569+
570--
571* `N`'s parent list had `I` removed, because it is an ancestor of the
572 other parent `M`. Still, `N` remained because it is !TREESAME.
573+
574* `P`'s parent list similarly had `I` removed. `P` was then
575 removed completely, because it had one parent and is TREESAME.
Junio C Hamano27159f82013-06-14 17:19:22576+
577* `Q`'s parent list had `Y` simplified to `X`. `X` was then removed, because it
578 was a TREESAME root. `Q` was then removed completely, because it had one
579 parent and is TREESAME.
Junio C Hamanoa2f46622008-09-03 05:20:31580--
Junio C Hamanob0e02952008-01-19 08:02:00581
Junio C Hamano67bf2242020-04-22 21:41:44582There is another simplification mode available:
Junio C Hamano89a57342010-06-22 23:22:55583
Junio C Hamano594d2d42022-08-30 17:58:50584--ancestry-path[=<commit>]::
585Limit the displayed commits to those which are an ancestor of
586<commit>, or which are a descendant of <commit>, or are <commit>
587itself.
Junio C Hamano89a57342010-06-22 23:22:55588+
589As an example use case, consider the following commit history:
590+
591-----------------------------------------------------------------------
592 D---E-------F
593 / \ \
594 B---C---G---H---I---J
595 / \
596A-------K---------------L--M
597-----------------------------------------------------------------------
598+
599A regular 'D..M' computes the set of commits that are ancestors of `M`,
600but excludes the ones that are ancestors of `D`. This is useful to see
601what happened to the history leading to `M` since `D`, in the sense
Junio C Hamanob73af6c2013-12-03 22:07:11602that ``what does `M` have that did not exist in `D`''. The result in this
Junio C Hamano89a57342010-06-22 23:22:55603example would be all the commits, except `A` and `B` (and `D` itself,
604of course).
605+
606When we want to find out what commits in `M` are contaminated with the
607bug introduced by `D` and need fixing, however, we might want to view
608only the subset of 'D..M' that are actually descendants of `D`, i.e.
Junio C Hamanob73af6c2013-12-03 22:07:11609excluding `C` and `K`. This is exactly what the `--ancestry-path`
Junio C Hamano89a57342010-06-22 23:22:55610option does. Applied to the 'D..M' range, it results in:
611+
612-----------------------------------------------------------------------
613E-------F
614 \ \
615 G---H---I---J
616 \
617L--M
618-----------------------------------------------------------------------
Junio C Hamano594d2d42022-08-30 17:58:50619+
620We can also use `--ancestry-path=D` instead of `--ancestry-path` which
621means the same thing when applied to the 'D..M' range but is just more
622explicit.
623+
624If we instead are interested in a given topic within this range, and all
625commits affected by that topic, we may only want to view the subset of
626`D..M` which contain that topic in their ancestry path. So, using
627`--ancestry-path=H D..M` for example would result in:
628+
629-----------------------------------------------------------------------
630E
631 \
632 G---H---I---J
633 \
634L--M
635-----------------------------------------------------------------------
636+
637Whereas `--ancestry-path=K D..M` would result in
638+
639-----------------------------------------------------------------------
640K---------------L--M
641-----------------------------------------------------------------------
Junio C Hamano89a57342010-06-22 23:22:55642
Junio C Hamano67bf2242020-04-22 21:41:44643Before discussing another option, `--show-pulls`, we need to
644create a new example history.
Junio C Hamano0cb719f2020-05-31 20:04:39645
Junio C Hamano67bf2242020-04-22 21:41:44646A common problem users face when looking at simplified history is that a
647commit they know changed a file somehow does not appear in the file's
648simplified history. Let's demonstrate a new example and show how options
649such as `--full-history` and `--simplify-merges` works in that case:
Junio C Hamano0cb719f2020-05-31 20:04:39650
Junio C Hamano67bf2242020-04-22 21:41:44651-----------------------------------------------------------------------
652 .-A---M-----C--N---O---P
653 / / \ \ \/ / /
654I B \ R-'`-Z' /
655 \ / \/ /
656 \ / /\ /
657 `---X--' `---Y--'
658-----------------------------------------------------------------------
Junio C Hamano0cb719f2020-05-31 20:04:39659
Junio C Hamano67bf2242020-04-22 21:41:44660For this example, suppose `I` created `file.txt` which was modified by
661`A`, `B`, and `X` in different ways. The single-parent commits `C`, `Z`,
662and `Y` do not change `file.txt`. The merge commit `M` was created by
663resolving the merge conflict to include both changes from `A` and `B`
664and hence is not TREESAME to either. The merge commit `R`, however, was
665created by ignoring the contents of `file.txt` at `M` and taking only
666the contents of `file.txt` at `X`. Hence, `R` is TREESAME to `X` but not
667`M`. Finally, the natural merge resolution to create `N` is to take the
668contents of `file.txt` at `R`, so `N` is TREESAME to `R` but not `C`.
669The merge commits `O` and `P` are TREESAME to their first parents, but
670not to their second parents, `Z` and `Y` respectively.
Junio C Hamano0cb719f2020-05-31 20:04:39671
Junio C Hamano67bf2242020-04-22 21:41:44672When using the default mode, `N` and `R` both have a TREESAME parent, so
673those edges are walked and the others are ignored. The resulting history
674graph is:
Junio C Hamano0cb719f2020-05-31 20:04:39675
Junio C Hamano67bf2242020-04-22 21:41:44676-----------------------------------------------------------------------
677I---X
678-----------------------------------------------------------------------
Junio C Hamano0cb719f2020-05-31 20:04:39679
Junio C Hamano67bf2242020-04-22 21:41:44680When using `--full-history`, Git walks every edge. This will discover
681the commits `A` and `B` and the merge `M`, but also will reveal the
682merge commits `O` and `P`. With parent rewriting, the resulting graph is:
Junio C Hamano0cb719f2020-05-31 20:04:39683
Junio C Hamano67bf2242020-04-22 21:41:44684-----------------------------------------------------------------------
685 .-A---M--------N---O---P
686 / / \ \ \/ / /
687I B \ R-'`--' /
688 \ / \/ /
689 \ / /\ /
690 `---X--' `------'
691-----------------------------------------------------------------------
Junio C Hamano0cb719f2020-05-31 20:04:39692
Junio C Hamano67bf2242020-04-22 21:41:44693Here, the merge commits `O` and `P` contribute extra noise, as they did
694not actually contribute a change to `file.txt`. They only merged a topic
695that was based on an older version of `file.txt`. This is a common
696issue in repositories using a workflow where many contributors work in
Junio C Hamano594d2d42022-08-30 17:58:50697parallel and merge their topic branches along a single trunk: many
Junio C Hamano67bf2242020-04-22 21:41:44698unrelated merges appear in the `--full-history` results.
Junio C Hamano0cb719f2020-05-31 20:04:39699
Junio C Hamano67bf2242020-04-22 21:41:44700When using the `--simplify-merges` option, the commits `O` and `P`
701disappear from the results. This is because the rewritten second parents
702of `O` and `P` are reachable from their first parents. Those edges are
703removed and then the commits look like single-parent commits that are
704TREESAME to their parent. This also happens to the commit `N`, resulting
705in a history view as follows:
Junio C Hamano0cb719f2020-05-31 20:04:39706
Junio C Hamano67bf2242020-04-22 21:41:44707-----------------------------------------------------------------------
708 .-A---M--.
709 / / \
710I B R
711 \ / /
712 \ / /
713 `---X--'
714-----------------------------------------------------------------------
Junio C Hamano0cb719f2020-05-31 20:04:39715
Junio C Hamano67bf2242020-04-22 21:41:44716In this view, we see all of the important single-parent changes from
717`A`, `B`, and `X`. We also see the carefully-resolved merge `M` and the
718not-so-carefully-resolved merge `R`. This is usually enough information
719to determine why the commits `A` and `B` "disappeared" from history in
720the default view. However, there are a few issues with this approach.
Junio C Hamano0cb719f2020-05-31 20:04:39721
Junio C Hamano67bf2242020-04-22 21:41:44722The first issue is performance. Unlike any previous option, the
723`--simplify-merges` option requires walking the entire commit history
724before returning a single result. This can make the option difficult to
725use for very large repositories.
Junio C Hamano0cb719f2020-05-31 20:04:39726
Junio C Hamano67bf2242020-04-22 21:41:44727The second issue is one of auditing. When many contributors are working
728on the same repository, it is important which merge commits introduced
729a change into an important branch. The problematic merge `R` above is
730not likely to be the merge commit that was used to merge into an
731important branch. Instead, the merge `N` was used to merge `R` and `X`
732into the important branch. This commit may have information about why
733the change `X` came to override the changes from `A` and `B` in its
734commit message.
Junio C Hamano0cb719f2020-05-31 20:04:39735
736--show-pulls::
737In addition to the commits shown in the default history, show
738each merge commit that is not TREESAME to its first parent but
739is TREESAME to a later parent.
Junio C Hamano67bf2242020-04-22 21:41:44740+
Junio C Hamano0cb719f2020-05-31 20:04:39741When a merge commit is included by `--show-pulls`, the merge is
Junio C Hamano67bf2242020-04-22 21:41:44742treated as if it "pulled" the change from another branch. When using
743`--show-pulls` on this example (and no other options) the resulting
744graph is:
745+
746-----------------------------------------------------------------------
747I---X---R---N
748-----------------------------------------------------------------------
749+
750Here, the merge commits `R` and `N` are included because they pulled
751the commits `X` and `R` into the base branch, respectively. These
752merges are the reason the commits `A` and `B` do not appear in the
753default history.
754+
755When `--show-pulls` is paired with `--simplify-merges`, the
756graph includes all of the necessary information:
757+
758-----------------------------------------------------------------------
759 .-A---M--. N
760 / / \ /
761I B R
762 \ / /
763 \ / /
764 `---X--'
765-----------------------------------------------------------------------
766+
767Notice that since `M` is reachable from `R`, the edge from `N` to `M`
768was simplified away. However, `N` still appears in the history as an
769important commit because it "pulled" the change `R` into the main
770branch.
771
Junio C Hamanob73af6c2013-12-03 22:07:11772The `--simplify-by-decoration` option allows you to view only the
Junio C Hamano28363492008-11-14 08:26:31773big picture of the topology of the history, by omitting commits
774that are not referenced by tags. Commits are marked as !TREESAME
775(in other words, kept after history simplification rules described
776above) if (1) they are referenced by tags, or (2) they change the
777contents of the paths given on the command line. All other
778commits are marked as TREESAME (subject to be simplified away).
779
Junio C Hamano8ef91f32019-12-01 22:58:27780ifndef::git-shortlog[]
Junio C Hamanob0e02952008-01-19 08:02:00781ifdef::git-rev-list[]
Junio C Hamanoa76cb0d2008-08-13 20:04:10782Bisection Helpers
783~~~~~~~~~~~~~~~~~
784
Junio C Hamanob0e02952008-01-19 08:02:00785--bisect::
Junio C Hamanob73af6c2013-12-03 22:07:11786Limit output to the one commit object which is roughly halfway between
787included and excluded commits. Note that the bad bisection ref
788`refs/bisect/bad` is added to the included commits (if it
789exists) and the good bisection refs `refs/bisect/good-*` are
790added to the excluded commits (if they exist). Thus, supposing there
791are no refs in `refs/bisect/`, if
792+
Junio C Hamanob0e02952008-01-19 08:02:00793-----------------------------------------------------------------------
Junio C Hamano175a1bd2008-11-10 00:08:57794$ git rev-list --bisect foo ^bar ^baz
Junio C Hamanob0e02952008-01-19 08:02:00795-----------------------------------------------------------------------
Junio C Hamanob73af6c2013-12-03 22:07:11796+
Junio C Hamanob0e02952008-01-19 08:02:00797outputs 'midpoint', the output of the two commands
Junio C Hamanob73af6c2013-12-03 22:07:11798+
Junio C Hamanob0e02952008-01-19 08:02:00799-----------------------------------------------------------------------
Junio C Hamano175a1bd2008-11-10 00:08:57800$ git rev-list foo ^midpoint
801$ git rev-list midpoint ^bar ^baz
Junio C Hamanob0e02952008-01-19 08:02:00802-----------------------------------------------------------------------
Junio C Hamanob73af6c2013-12-03 22:07:11803+
Junio C Hamanob0e02952008-01-19 08:02:00804would be of roughly the same length. Finding the change which
805introduces a regression is thus reduced to a binary search: repeatedly
806generate and test new 'midpoint's until the commit chain is of length
Junio C Hamano255163d2020-08-18 00:37:23807one.
Junio C Hamanob0e02952008-01-19 08:02:00808
809--bisect-vars::
Junio C Hamanob73af6c2013-12-03 22:07:11810This calculates the same as `--bisect`, except that refs in
811`refs/bisect/` are not used, and except that this outputs
812text ready to be eval'ed by the shell. These lines will assign the
813name of the midpoint revision to the variable `bisect_rev`, and the
814expected number of commits to be tested after `bisect_rev` is tested
815to `bisect_nr`, the expected number of commits to be tested if
816`bisect_rev` turns out to be good to `bisect_good`, the expected
817number of commits to be tested if `bisect_rev` turns out to be bad to
818`bisect_bad`, and the number of commits we are bisecting right now to
819`bisect_all`.
Junio C Hamanob0e02952008-01-19 08:02:00820
821--bisect-all::
Junio C Hamanob73af6c2013-12-03 22:07:11822This outputs all the commit objects between the included and excluded
823commits, ordered by their distance to the included and excluded
824commits. Refs in `refs/bisect/` are not used. The farthest
825from them is displayed first. (This is the only one displayed by
826`--bisect`.)
Junio C Hamano792c5a92009-03-08 08:45:13827+
Junio C Hamanob0e02952008-01-19 08:02:00828This is useful because it makes it easy to choose a good commit to
829test when you want to avoid to test some of them for some reason (they
830may not compile for example).
Junio C Hamano792c5a92009-03-08 08:45:13831+
Junio C Hamanob0e02952008-01-19 08:02:00832This option can be used along with `--bisect-vars`, in this case,
833after all the sorted commit objects, there will be the same text as if
834`--bisect-vars` had been used alone.
835endif::git-rev-list[]
Junio C Hamano8ef91f32019-12-01 22:58:27836endif::git-shortlog[]
Junio C Hamanob0e02952008-01-19 08:02:00837
Junio C Hamano8ef91f32019-12-01 22:58:27838ifndef::git-shortlog[]
Junio C Hamanob0e02952008-01-19 08:02:00839Commit Ordering
840~~~~~~~~~~~~~~~
841
842By default, the commits are shown in reverse chronological order.
843
Junio C Hamanob0e02952008-01-19 08:02:00844--date-order::
Junio C Hamanod0316112012-08-22 19:55:29845Show no parents before all of its children are shown, but
846otherwise show commits in the commit timestamp order.
Junio C Hamanob0e02952008-01-19 08:02:00847
Junio C Hamanoa1952302013-07-01 21:31:18848--author-date-order::
849Show no parents before all of its children are shown, but
850otherwise show commits in the author timestamp order.
851
Junio C Hamanod0316112012-08-22 19:55:29852--topo-order::
853Show no parents before all of its children are shown, and
854avoid showing commits on multiple lines of history
855intermixed.
856+
857For example, in a commit history like this:
858+
859----------------------------------------------------------------
860
861 ---1----2----4----7
862\ \
863 3----5----6----8---
864
865----------------------------------------------------------------
866+
867where the numbers denote the order of commit timestamps, `git
868rev-list` and friends with `--date-order` show the commits in the
869timestamp order: 8 7 6 5 4 3 2 1.
870+
871With `--topo-order`, they would show 8 6 5 3 7 4 2 1 (or 8 7 4 2 6 5
8723 1); some older commits are shown before newer ones in order to
873avoid showing the commits from two parallel development track mixed
874together.
Junio C Hamanob0e02952008-01-19 08:02:00875
876--reverse::
Junio C Hamanof3ca7b82016-10-03 22:27:02877Output the commits chosen to be shown (see Commit Limiting
878section above) in reverse order. Cannot be combined with
879`--walk-reflogs`.
Junio C Hamano8ef91f32019-12-01 22:58:27880endif::git-shortlog[]
Junio C Hamanob0e02952008-01-19 08:02:00881
Junio C Hamano8ef91f32019-12-01 22:58:27882ifndef::git-shortlog[]
Junio C Hamanob0e02952008-01-19 08:02:00883Object Traversal
884~~~~~~~~~~~~~~~~
885
Junio C Hamano076ffcc2013-02-06 05:13:21886These options are mostly targeted for packing of Git repositories.
Junio C Hamanob0e02952008-01-19 08:02:00887
Junio C Hamano6bb32e62015-02-17 22:11:26888ifdef::git-rev-list[]
Junio C Hamanob0e02952008-01-19 08:02:00889--objects::
Junio C Hamanob0e02952008-01-19 08:02:00890Print the object IDs of any object referenced by the listed
Junio C Hamanob73af6c2013-12-03 22:07:11891commits. `--objects foo ^bar` thus means ``send me
Junio C Hamanob0e02952008-01-19 08:02:00892all object IDs which I need to download if I have the commit
Junio C Hamanob73af6c2013-12-03 22:07:11893object _bar_ but not _foo_''.
Junio C Hamanob0e02952008-01-19 08:02:00894
Junio C Hamano68e72b72017-12-28 23:20:52895--in-commit-order::
896Print tree and blob ids in order of the commits. The tree
897and blob ids are printed after they are first referenced
898by a commit.
899
Junio C Hamanob0e02952008-01-19 08:02:00900--objects-edge::
Junio C Hamanob73af6c2013-12-03 22:07:11901Similar to `--objects`, but also print the IDs of excluded
902commits prefixed with a ``-'' character. This is used by
Junio C Hamano629edff2015-01-12 23:46:02903linkgit:git-pack-objects[1] to build a ``thin'' pack, which records
Junio C Hamanob0e02952008-01-19 08:02:00904objects in deltified form based on objects contained in these
905excluded commits to reduce network traffic.
906
Junio C Hamano629edff2015-01-12 23:46:02907--objects-edge-aggressive::
908Similar to `--objects-edge`, but it tries harder to find excluded
909commits at the cost of increased time. This is used instead of
910`--objects-edge` to build ``thin'' packs for shallow repositories.
911
Junio C Hamano6bb32e62015-02-17 22:11:26912--indexed-objects::
913Pretend as if all trees and blobs used by the index are listed
914on the command line. Note that you probably want to use
915`--objects`, too.
916
Junio C Hamanob0e02952008-01-19 08:02:00917--unpacked::
Junio C Hamanob73af6c2013-12-03 22:07:11918Only useful with `--objects`; print the object IDs that are not
Junio C Hamanob0e02952008-01-19 08:02:00919in packs.
Junio C Hamano0f1291d2017-12-27 19:58:35920
Junio C Hamanoc9f11c22019-07-10 02:54:04921--object-names::
922Only useful with `--objects`; print the names of the object IDs
923that are found. This is the default behavior.
924
925--no-object-names::
926Only useful with `--objects`; does not print the names of the object
927IDs that are found. This inverts `--object-names`. This flag allows
928the output to be more easily parsed by commands such as
929linkgit:git-cat-file[1].
930
Junio C Hamano0f1291d2017-12-27 19:58:35931--filter=<filter-spec>::
932Only useful with one of the `--objects*`; omits objects (usually
933blobs) from the list of printed objects. The '<filter-spec>'
934may be one of the following:
935+
936The form '--filter=blob:none' omits all blobs.
937+
938The form '--filter=blob:limit=<n>[kmg]' omits blobs larger than n bytes
939or units. n may be zero. The suffixes k, m, and g can be used to name
940units in KiB, MiB, or GiB. For example, 'blob:limit=1k' is the same
941as 'blob:limit=1024'.
942+
Junio C Hamanobe601db2021-05-07 04:20:28943The form '--filter=object:type=(tag|commit|tree|blob)' omits all objects
944which are not of the requested type.
945+
Junio C Hamano0f1291d2017-12-27 19:58:35946The form '--filter=sparse:oid=<blob-ish>' uses a sparse-checkout
947specification contained in the blob (or blob-expression) '<blob-ish>'
Junio C Hamano20cf4932021-07-28 21:02:52948to omit blobs that would not be required for a sparse checkout on
Junio C Hamano0f1291d2017-12-27 19:58:35949the requested refs.
950+
Junio C Hamano94d00a52018-10-30 07:34:40951The form '--filter=tree:<depth>' omits all blobs and trees whose depth
952from the root tree is >= <depth> (minimum depth if an object is located
Junio C Hamano2567b322019-02-05 23:33:56953at multiple depths in the commits traversed). <depth>=0 will not include
954any trees or blobs unless included explicitly in the command-line (or
955standard input when --stdin is used). <depth>=1 will include only the
956tree and blobs which are referenced directly by a commit reachable from
957<commit> or an explicitly-given object. <depth>=2 is like <depth>=1
958while also including trees and blobs one more level removed from an
959explicitly-given commit or tree.
Junio C Hamano0887d042019-06-03 19:55:17960+
961Note that the form '--filter=sparse:path=<path>' that wants to read
962from an arbitrary path on the filesystem has been dropped for security
963reasons.
Junio C Hamanocb705392019-09-18 19:30:01964+
965Multiple '--filter=' flags can be specified to combine filters. Only
966objects which are accepted by every filter are included.
967+
968The form '--filter=combine:<filter1>+<filter2>+...<filterN>' can also be
969used to combined several filters, but this is harder than just repeating
970the '--filter' flag and is usually not necessary. Filters are joined by
971'{plus}' and individual filters are %-encoded (i.e. URL-encoded).
972Besides the '{plus}' and '%' characters, the following characters are
973reserved and also must be encoded: `~!@#$^&*()[]{}\;",<>?`+&#39;&#96;+
974as well as all characters with ASCII code &lt;= `0x20`, which includes
975space and newline.
976+
977Other arbitrary characters can also be encoded. For instance,
978'combine:tree:3+blob:none' and 'combine:tree%3A3+blob%3Anone' are
979equivalent.
Junio C Hamano0f1291d2017-12-27 19:58:35980
981--no-filter::
982Turn off any previous `--filter=` argument.
983
Junio C Hamanobe601db2021-05-07 04:20:28984--filter-provided-objects::
985Filter the list of explicitly provided objects, which would otherwise
986always be printed even if they did not match any of the filters. Only
987useful with `--filter=`.
988
Junio C Hamano0f1291d2017-12-27 19:58:35989--filter-print-omitted::
990Only useful with `--filter=`; prints a list of the objects omitted
Junio C Hamano6b7d2152019-04-16 12:51:15991by the filter. Object IDs are prefixed with a ``~'' character.
Junio C Hamano0f1291d2017-12-27 19:58:35992
993--missing=<missing-action>::
994A debug option to help with future "partial clone" development.
995This option specifies how missing objects are handled.
996+
997The form '--missing=error' requests that rev-list stop with an error if
998a missing object is encountered. This is the default action.
999+
1000The form '--missing=allow-any' will allow object traversal to continue
1001if a missing object is encountered. Missing objects will silently be
1002omitted from the results.
1003+
Junio C Hamano640779d2018-02-14 01:29:141004The form '--missing=allow-promisor' is like 'allow-any', but will only
1005allow object traversal to continue for EXPECTED promisor missing objects.
1006Unexpected missing objects will raise an error.
1007+
Junio C Hamano0f1291d2017-12-27 19:58:351008The form '--missing=print' is like 'allow-any', but will also print a
1009list of the missing objects. Object IDs are prefixed with a ``?'' character.
Junio C Hamanob0e02952008-01-19 08:02:001010
Junio C Hamano640779d2018-02-14 01:29:141011--exclude-promisor-objects::
1012(For internal use only.) Prefilter object traversal at
1013promisor boundary. This is used with partial clone. This is
1014stronger than `--missing=allow-promisor` because it limits the
1015traversal, rather than just silencing errors about missing
1016objects.
Junio C Hamano46fbbcb2018-11-07 03:54:161017endif::git-rev-list[]
Junio C Hamano640779d2018-02-14 01:29:141018
Junio C Hamanoeccdd4a2012-09-10 23:28:171019--no-walk[=(sorted|unsorted)]::
Junio C Hamanoeccdd4a2012-09-10 23:28:171020Only show the given commits, but do not traverse their ancestors.
1021This has no effect if a range is specified. If the argument
Junio C Hamanob73af6c2013-12-03 22:07:111022`unsorted` is given, the commits are shown in the order they were
1023given on the command line. Otherwise (if `sorted` or no argument
1024was given), the commits are shown in reverse chronological order
Junio C Hamanoeccdd4a2012-09-10 23:28:171025by commit time.
Junio C Hamanoe8fdbbb2021-11-12 23:42:031026Cannot be combined with `--graph`.
Junio C Hamanob0e02952008-01-19 08:02:001027
1028--do-walk::
Junio C Hamanob73af6c2013-12-03 22:07:111029Overrides a previous `--no-walk`.
Junio C Hamano8ef91f32019-12-01 22:58:271030endif::git-shortlog[]
Junio C Hamanod2c978f2011-03-20 19:42:221031
Junio C Hamano8ef91f32019-12-01 22:58:271032ifndef::git-shortlog[]
Junio C Hamanod2c978f2011-03-20 19:42:221033Commit Formatting
1034~~~~~~~~~~~~~~~~~
1035
1036ifdef::git-rev-list[]
1037Using these options, linkgit:git-rev-list[1] will act similar to the
1038more specialized family of commit log tools: linkgit:git-log[1],
1039linkgit:git-show[1], and linkgit:git-whatchanged[1]
1040endif::git-rev-list[]
1041
1042include::pretty-options.txt[]
1043
1044--relative-date::
Junio C Hamanod2c978f2011-03-20 19:42:221045Synonym for `--date=relative`.
1046
Junio C Hamano1eb56092015-10-05 20:39:531047--date=<format>::
Junio C Hamanod2c978f2011-03-20 19:42:221048Only takes effect for dates shown in human-readable format, such
Junio C Hamanob73af6c2013-12-03 22:07:111049as when using `--pretty`. `log.date` config variable sets a default
Junio C Hamano1eb56092015-10-05 20:39:531050value for the log command's `--date` option. By default, dates
1051are shown in the original time zone (either committer's or
1052author's). If `-local` is appended to the format (e.g.,
1053`iso-local`), the user's local time zone is used instead.
Junio C Hamanod2c978f2011-03-20 19:42:221054+
Junio C Hamanob5513772019-04-22 03:38:391055--
Junio C Hamanod2c978f2011-03-20 19:42:221056`--date=relative` shows dates relative to the current time,
Junio C Hamanoe548d1b2016-08-08 22:26:491057e.g. ``2 hours ago''. The `-local` option has no effect for
1058`--date=relative`.
Junio C Hamanob5513772019-04-22 03:38:391059
Junio C Hamano1eb56092015-10-05 20:39:531060`--date=local` is an alias for `--date=default-local`.
Junio C Hamanob5513772019-04-22 03:38:391061
Junio C Hamanoac12f0e2014-09-19 22:32:511062`--date=iso` (or `--date=iso8601`) shows timestamps in a ISO 8601-like format.
1063The differences to the strict ISO 8601 format are:
1064
1065- a space instead of the `T` date/time delimiter
1066- a space between time and time zone
1067- no colon between hours and minutes of the time zone
1068
Junio C Hamanoac12f0e2014-09-19 22:32:511069`--date=iso-strict` (or `--date=iso8601-strict`) shows timestamps in strict
1070ISO 8601 format.
Junio C Hamanob5513772019-04-22 03:38:391071
Junio C Hamanod2c978f2011-03-20 19:42:221072`--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822
Junio C Hamanob73af6c2013-12-03 22:07:111073format, often found in email messages.
Junio C Hamanob5513772019-04-22 03:38:391074
Junio C Hamanob73af6c2013-12-03 22:07:111075`--date=short` shows only the date, but not the time, in `YYYY-MM-DD` format.
Junio C Hamanob5513772019-04-22 03:38:391076
Junio C Hamanoe548d1b2016-08-08 22:26:491077`--date=raw` shows the date as seconds since the epoch (1970-01-01
107800:00:00 UTC), followed by a space, and then the timezone as an offset
1079from UTC (a `+` or `-` with four digits; the first two are hours, and
1080the second two are minutes). I.e., as if the timestamp were formatted
1081with `strftime("%s %z")`).
1082Note that the `-local` option does not affect the seconds-since-epoch
1083value (which is always measured in UTC), but does switch the accompanying
1084timezone value.
Junio C Hamanob5513772019-04-22 03:38:391085
Junio C Hamano23168ef2019-02-07 07:20:471086`--date=human` shows the timezone if the timezone does not match the
1087current time-zone, and doesn't print the whole date if that matches
1088(ie skip printing year for dates that are "this year", but also skip
1089the whole date itself if it's in the last few days and we can just say
1090what weekday it was). For older dates the hour and minute is also
1091omitted.
Junio C Hamanob5513772019-04-22 03:38:391092
Junio C Hamanoe548d1b2016-08-08 22:26:491093`--date=unix` shows the date as a Unix epoch timestamp (seconds since
10941970). As with `--raw`, this is always in UTC and therefore `-local`
1095has no effect.
Junio C Hamanob5513772019-04-22 03:38:391096
Junio C Hamano55d91912017-06-22 22:32:461097`--date=format:...` feeds the format `...` to your system `strftime`,
Junio C Hamano59a32b02021-12-10 22:53:381098except for %s, %z, and %Z, which are handled internally.
Junio C Hamanod7ed4042015-08-03 19:43:001099Use `--date=format:%c` to show the date in your system locale's
1100preferred format. See the `strftime` manual for a complete list of
Junio C Hamano1eb56092015-10-05 20:39:531101format placeholders. When using `-local`, the correct syntax is
1102`--date=format-local:...`.
Junio C Hamanob5513772019-04-22 03:38:391103
Junio C Hamano613334c2023-02-24 19:54:381104`--date=default` is the default format, and is based on ctime(3)
1105output. It shows a single line with three-letter day of the week,
1106three-letter month, day-of-month, hour-minute-seconds in "HH:MM:SS"
1107format, followed by 4-digit year, plus timezone information, unless
1108the local time zone is used, e.g. `Thu Jan 1 00:00:00 1970 +0000`.
Junio C Hamanob5513772019-04-22 03:38:391109--
Junio C Hamanod2c978f2011-03-20 19:42:221110
1111ifdef::git-rev-list[]
1112--header::
Junio C Hamanod2c978f2011-03-20 19:42:221113Print the contents of the commit in raw-format; each record is
1114separated with a NUL character.
Junio C Hamano20cf4932021-07-28 21:02:521115
1116--no-commit-header::
1117Suppress the header line containing "commit" and the object ID printed before
1118the specified format. This has no effect on the built-in formats; only custom
1119formats are affected.
1120
1121--commit-header::
1122Overrides a previous `--no-commit-header`.
Junio C Hamanod2c978f2011-03-20 19:42:221123endif::git-rev-list[]
1124
1125--parents::
Junio C Hamanod2c978f2011-03-20 19:42:221126Print also the parents of the commit (in the form "commit parent...").
Junio C Hamanoce019c02017-10-30 05:57:461127Also enables parent rewriting, see 'History Simplification' above.
Junio C Hamanod2c978f2011-03-20 19:42:221128
1129--children::
Junio C Hamanod2c978f2011-03-20 19:42:221130Print also the children of the commit (in the form "commit child...").
Junio C Hamanoce019c02017-10-30 05:57:461131Also enables parent rewriting, see 'History Simplification' above.
Junio C Hamanod2c978f2011-03-20 19:42:221132
1133ifdef::git-rev-list[]
1134--timestamp::
1135Print the raw commit timestamp.
1136endif::git-rev-list[]
1137
1138--left-right::
Junio C Hamanocd451662016-09-13 00:54:091139Mark which side of a symmetric difference a commit is reachable from.
Junio C Hamanod2c978f2011-03-20 19:42:221140Commits from the left side are prefixed with `<` and those from
1141the right with `>`. If combined with `--boundary`, those
1142commits are prefixed with `-`.
1143+
1144For example, if you have this topology:
1145+
1146-----------------------------------------------------------------------
1147 y---b---b branch B
1148 / \ /
1149 / .
1150 / / \
1151 o---x---a---a branch A
1152-----------------------------------------------------------------------
1153+
1154you would get an output like this:
1155+
1156-----------------------------------------------------------------------
1157$ git rev-list --left-right --boundary --pretty=oneline A...B
1158
1159>bbbbbbb... 3rd on b
1160>bbbbbbb... 2nd on b
1161<aaaaaaa... 3rd on a
1162<aaaaaaa... 2nd on a
1163-yyyyyyy... 1st on b
1164-xxxxxxx... 1st on a
1165-----------------------------------------------------------------------
1166
1167--graph::
Junio C Hamanod2c978f2011-03-20 19:42:221168Draw a text-based graphical representation of the commit history
1169on the left hand side of the output. This may cause extra lines
1170to be printed in between commits, in order for the graph history
1171to be drawn properly.
Junio C Hamanoef57d1e2015-03-25 21:23:001172Cannot be combined with `--no-walk`.
Junio C Hamanod2c978f2011-03-20 19:42:221173+
Junio C Hamanoce019c02017-10-30 05:57:461174This enables parent rewriting, see 'History Simplification' above.
Junio C Hamanod2c978f2011-03-20 19:42:221175+
Junio C Hamanob73af6c2013-12-03 22:07:111176This implies the `--topo-order` option by default, but the
1177`--date-order` option may also be specified.
Junio C Hamanod2c978f2011-03-20 19:42:221178
Junio C Hamano624dd4c2014-04-03 21:56:301179--show-linear-break[=<barrier>]::
1180When --graph is not used, all history branches are flattened
1181which can make it hard to see that the two consecutive commits
1182do not belong to a linear branch. This option puts a barrier
1183in between them in that case. If `<barrier>` is specified, it
1184is the string that will be shown instead of the default one.
1185
Junio C Hamanod2c978f2011-03-20 19:42:221186ifdef::git-rev-list[]
1187--count::
1188Print a number stating how many commits would have been
1189listed, and suppress all other output. When used together
Junio C Hamanob73af6c2013-12-03 22:07:111190with `--left-right`, instead print the counts for left and
Junio C Hamanob77f8192011-05-05 01:30:381191right commits, separated by a tab. When used together with
Junio C Hamanob73af6c2013-12-03 22:07:111192`--cherry-mark`, omit patch equivalent commits from these
Junio C Hamanob77f8192011-05-05 01:30:381193counts and print the count for equivalent commits separated
1194by a tab.
Junio C Hamanod2c978f2011-03-20 19:42:221195endif::git-rev-list[]
Junio C Hamano8ef91f32019-12-01 22:58:271196endif::git-shortlog[]